<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.9: http://docutils.sourceforge.net/" />
<title>Extending RepastCity</title>
<style type="text/css">

/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
:Copyright: This stylesheet has been placed in the public domain.

Default cascading style sheet for the HTML output of Docutils.

See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/

/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
  border: 0 }

table.borderless td, table.borderless th {
  /* Override padding for "table.docutils td" with "! important".
     The right padding separates the table cells. */
  padding: 0 0.5em 0 0 ! important }

.first {
  /* Override more specific margin styles with "! important". */
  margin-top: 0 ! important }

.last, .with-subtitle {
  margin-bottom: 0 ! important }

.hidden {
  display: none }

a.toc-backref {
  text-decoration: none ;
  color: black }

blockquote.epigraph {
  margin: 2em 5em ; }

dl.docutils dd {
  margin-bottom: 0.5em }

object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
  overflow: hidden;
}

/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
  font-weight: bold }
*/

div.abstract {
  margin: 2em 5em }

div.abstract p.topic-title {
  font-weight: bold ;
  text-align: center }

div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
  margin: 2em ;
  border: medium outset ;
  padding: 1em }

div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
  font-weight: bold ;
  font-family: sans-serif }

div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
  color: red ;
  font-weight: bold ;
  font-family: sans-serif }

/* Uncomment (and remove this text!) to get reduced vertical space in
   compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
  margin-bottom: 0.5em }

div.compound .compound-last, div.compound .compound-middle {
  margin-top: 0.5em }
*/

div.dedication {
  margin: 2em 5em ;
  text-align: center ;
  font-style: italic }

div.dedication p.topic-title {
  font-weight: bold ;
  font-style: normal }

div.figure {
  margin-left: 2em ;
  margin-right: 2em }

div.footer, div.header {
  clear: both;
  font-size: smaller }

div.line-block {
  display: block ;
  margin-top: 1em ;
  margin-bottom: 1em }

div.line-block div.line-block {
  margin-top: 0 ;
  margin-bottom: 0 ;
  margin-left: 1.5em }

div.sidebar {
  margin: 0 0 0.5em 1em ;
  border: medium outset ;
  padding: 1em ;
  background-color: #ffffee ;
  width: 40% ;
  float: right ;
  clear: right }

div.sidebar p.rubric {
  font-family: sans-serif ;
  font-size: medium }

div.system-messages {
  margin: 5em }

div.system-messages h1 {
  color: red }

div.system-message {
  border: medium outset ;
  padding: 1em }

div.system-message p.system-message-title {
  color: red ;
  font-weight: bold }

div.topic {
  margin: 2em }

h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
  margin-top: 0.4em }

h1.title {
  text-align: center }

h2.subtitle {
  text-align: center }

hr.docutils {
  width: 75% }

img.align-left, .figure.align-left, object.align-left {
  clear: left ;
  float: left ;
  margin-right: 1em }

img.align-right, .figure.align-right, object.align-right {
  clear: right ;
  float: right ;
  margin-left: 1em }

img.align-center, .figure.align-center, object.align-center {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.align-left {
  text-align: left }

.align-center {
  clear: both ;
  text-align: center }

.align-right {
  text-align: right }

/* reset inner alignment in figures */
div.align-right {
  text-align: inherit }

/* div.align-center * { */
/*   text-align: left } */

ol.simple, ul.simple {
  margin-bottom: 1em }

ol.arabic {
  list-style: decimal }

ol.loweralpha {
  list-style: lower-alpha }

ol.upperalpha {
  list-style: upper-alpha }

ol.lowerroman {
  list-style: lower-roman }

ol.upperroman {
  list-style: upper-roman }

p.attribution {
  text-align: right ;
  margin-left: 50% }

p.caption {
  font-style: italic }

p.credits {
  font-style: italic ;
  font-size: smaller }

p.label {
  white-space: nowrap }

p.rubric {
  font-weight: bold ;
  font-size: larger ;
  color: maroon ;
  text-align: center }

p.sidebar-title {
  font-family: sans-serif ;
  font-weight: bold ;
  font-size: larger }

p.sidebar-subtitle {
  font-family: sans-serif ;
  font-weight: bold }

p.topic-title {
  font-weight: bold }

pre.address {
  margin-bottom: 0 ;
  margin-top: 0 ;
  font: inherit }

pre.literal-block, pre.doctest-block, pre.math {
  margin-left: 2em ;
  margin-right: 2em }

span.classifier {
  font-family: sans-serif ;
  font-style: oblique }

span.classifier-delimiter {
  font-family: sans-serif ;
  font-weight: bold }

span.interpreted {
  font-family: sans-serif }

span.option {
  white-space: nowrap }

span.pre {
  white-space: pre }

span.problematic {
  color: red }

span.section-subtitle {
  /* font-size relative to parent (h1..h6 element) */
  font-size: 80% }

table.citation {
  border-left: solid 1px gray;
  margin-left: 1px }

table.docinfo {
  margin: 2em 4em }

table.docutils {
  margin-top: 0.5em ;
  margin-bottom: 0.5em }

table.footnote {
  border-left: solid 1px black;
  margin-left: 1px }

table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
  padding-left: 0.5em ;
  padding-right: 0.5em ;
  vertical-align: top }

table.docutils th.field-name, table.docinfo th.docinfo-name {
  font-weight: bold ;
  text-align: left ;
  white-space: nowrap ;
  padding-left: 0 }

h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
  font-size: 100% }

ul.auto-toc {
  list-style-type: none }

</style>
</head>
<body>
<div class="document" id="extending-repastcity">
<h1 class="title">Extending RepastCity</h1>

<p>This page provides instructions describing how the model can be extended to suit individual applications.</p>
<div class="section" id="using-new-input-data">
<h1>Using New Input Data</h1>
<p>The most obvious requirement will to replace the demo data included with the model with something more realistic. The model reads spatial data in <a class="reference external" href="http://en.wikipedia.org/wiki/Shapefile">Shapefile</a> format which is a proprietary format used by ESRI ArcGIS. There are many (open source) programs that can be used to read or edit shapefile data (see <a class="reference external" href="http://www.qgis.org/">QuantumGIS</a> for example) if ArcGIS is not available.</p>
<p>The virtual 'city' consists of <em>roads</em> and <em>buildings</em> (note that in later versions  <em>communities</em> will also be used). For the default model, all the shapefile data are stored in the <tt class="docutils literal">data/gis_data/toy_city</tt> directory. This directory can be changed by editing the <tt class="docutils literal">repastcity.properties</tt> file and editing the line:</p>
<blockquote>
<tt class="docutils literal"><span class="pre">GISDataDirectory=./data/gis_data/toy_city/</span></tt></blockquote>
<p>The text '<tt class="docutils literal">./data/gis_data/toy_city/</tt>' can be replaced with the root directory of other GIS data. The model will expect to be able to read the files <tt class="docutils literal">roads.shp</tt> and <tt class="docutils literal">buildings.shp</tt>. Note that a shapefile is actually a collection of files so if other GIS data are used it is important to copy all files to the new directory, not just the <tt class="docutils literal">.shp</tt> files.</p>
<div class="section" id="requirements-for-road-data">
<h2>Requirements for road data</h2>
<p>There are some specific requirements for road data. Firstly, there cannot be any disconnected roads - the entire network must be joined together. Also, the model requires that if two roads cross then the line objects break at the point that they cross (the intersection). If this requirement is not met then the model will probably not crash, but routing will not work properly. The <a class="reference external" href="http://help.arcgis.com/en/arcgisdesktop/10.0/help/index.html#//001t0000008t000000.htm">Planarize Lines</a> function in ArcGIS is able to convert data to this form.</p>
</div>
</div>
<div class="section" id="agent-home-locations">
<h1>Agent Home Locations</h1>
<p>The starting locations of the agents can be changed in a similar manner to the other spatial data. The model searches the GIS data directory (<tt class="docutils literal">data/gis_data/toy_city</tt> by default) for a shapefile of points called <tt class="docutils literal">people.shp</tt>. It then reads that shapefile and creates an agent at each point. If the agent falls within a building it will set that building to be the agent's home. Therefore, <tt class="docutils literal">people.shp</tt> can be replaced with another file to change the starting locations (and number of) agents.</p>
<p>It is also possible to create a number of agents in randomly chosen buildings rather than reading their locations from a file. To do this, follow these steps:</p>
<ol class="arabic">
<li><p class="first">Start the model.</p>
</li>
<li><p class="first">In the bottom-right corner of the model window click on the left arrow (next to <cite>Scenario Tree</cite>). This should change the left frame to show model parameters.</p>
</li>
<li><dl class="first docutils">
<dt>In the <cite>Agent Definition</cite>, replace the text <cite>point:people.shp$repastcity3.agent.DefaultAgent</cite> with:</dt>
<dd><p class="first last">'random:N'
(where N is the number of agents to create, e.g. <tt class="docutils literal">random:25</tt>).</p>
</dd>
</dl>
</li>
<li><p class="first">Press the 'save' icon to remember the change (optional).</p>
</li>
<li><p class="first">Run the model.</p>
</li>
</ol>
<img alt="figures/agent_definition_gui.png" src="figures/agent_definition_gui.png" />
<p>For more information about the different ways to create agents, see the Java documentation for the <tt class="docutils literal">repastcity3.agent.AgentFactory</tt> class.</p>
</div>
<div class="section" id="agent-behaviour">
<h1>Agent Behaviour</h1>
<div class="section" id="method-1-edit-step">
<h2>Method 1 - Edit <tt class="docutils literal">step()</tt></h2>
<p>By default, RepastCity creates agents of the type  <tt class="docutils literal">repastcity3.agent.DefaultAgent</tt>. The <tt class="docutils literal">DefaultAgent.java</tt> source file contains a method called <tt class="docutils literal">step()</tt>; this is the one that is called at each iteration and controls how the agents behave. Hence the simplest way to change agent behaviour is to change the code in this method.</p>
<p>By default, each agent chooses a building at random, travels there, and then travels home again. The following code illustrates how this can be accomplished:</p>
<pre class="literal-block">
&#64;Override
public void step() throws Exception {
        // See if the agent has a route object (this controls their movement).
        if (this.route == null) { // No route object, create one.
                this.goingHome = false;
                // Choose a new building to travel to
                Building b = ContextManager.buildingContext.getRandomObject();
                this.route = new Route(this, b.getCoords(), b);
        }

        // See if the agent has reached their destination or if they need to keep travelling
        if (!this.route.atDestination()) {
                this.route.travel();
        }
        else {
                // Have reached destination, now either go home or onto another building
                if (this.goingHome) {
                        this.goingHome = false;
                        Building b = ContextManager.buildingContext.getRandomObject();
                        this.route = new Route(this, b.getCoords(), b);
                } else {
                        this.goingHome = true;
                        this.route = new Route(this, this.home.getCoords(), this.home);
                }
        }
} // step()
</pre>
</div>
<div class="section" id="method-2-implement-iagent">
<h2>Method 2 - Implement <tt class="docutils literal">IAgent</tt></h2>
<p>Alternatively, it is possible to provide a completely new agent type (or many different types in the same model). This can be achieved by creating a new class that implements the <tt class="docutils literal">IAgent</tt> interface. Then, to tell the model to use this new type, rather than <tt class="docutils literal">DefaultAgent</tt>, follow these steps:</p>
<ol class="arabic">
<li><p class="first">Start the model.</p>
</li>
<li><p class="first">In the bottom-right corner of the model window click on the left arrow (next to <cite>Scenario Tree</cite>). This should change the left frame to show model parameters.</p>
</li>
<li><dl class="first docutils">
<dt>In the <cite>Agent Definition</cite>, replace the text <cite>point:people.shp$repastcity3.agent.DefaultAgent</cite> with the name of the new class. For example, if the class were called <tt class="docutils literal">MyAgent</tt> and belonged to the package <tt class="docutils literal">repastcity3.new_agents</tt> the entry would be:</dt>
<dd><p class="first last"><tt class="docutils literal">point:people.shp$repastcity3.new_agents.MyAgent</tt></p>
</dd>
</dl>
</li>
<li><p class="first">Press the 'save' icon to remember the change (optional).</p>
</li>
<li><p class="first">Run the model.</p>
</li>
</ol>
<p>Note that if a new agent type is used this new agent type must be added to the display or it will not be shown when the model is running. The existing display only shows objects of type <tt class="docutils literal">DefaultAgent</tt>.</p>
</div>
</div>
</div>
</body>
</html>
